<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>vb2Py - Subroutines</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="vb2py-subroutines">
<h1 class="title">vb2Py - Subroutines</h1>
<!-- filename: c:\development\python22\lib\site-packages\vb2py\doc/sub.htm -->
<p>Contents of this page:</p>
<ul class="simple">
<li><a class="reference" href="#general">General</a></li>
<li><a class="reference" href="#default-conversion">Default Conversion</a></li>
<li><a class="reference" href="#list-of-options">List of Options</a></li>
</ul>
<p>Additional</p>
<ul class="simple">
<li><a class="reference" href="#missing-arguments">Missing Arguments</a></li>
<li><a class="reference" href="#argument-passing">Argument passing</a></li>
</ul>
<div class="section" id="general">
<h1><a name="general">General</a></h1>
<p>Subroutines are converted to Python functions with no return statement. Local variables in the VB subroutine are also local in the Python version. If a module global is used on the left hand side of an assignment then a Python <tt class="literal"><span class="pre">global</span></tt> statement will be inserted at the head of the function. Project <em>globals</em> will be replaced by their fully-qualified versions.</p>
</div>
<div class="section" id="default-conversion">
<h1><a name="default-conversion">Default Conversion</a></h1>
<p>VB:</p>
<pre class="literal-block">
Dim moduleGlobal1, moduleGlobal2

Sub MySub(X, Optional Y, Optional Z=20)
    Dim subLocal
    subLocal = X + Y + Z + moduleGlobal
    moduleGlobal2 = moduleGlobal2 + 1
End Sub

MySub 1, 2
MySub 1, Z:=10
</pre>
<div class="section" id="missing-arguments">
<h2><a name="missing-arguments">Missing Arguments</a></h2>
<p>Optional arguments which are not supplied and have no defaults are initialized with the <tt class="literal"><span class="pre">VBMissingArgument</span></tt> object. This object can be detected by the <tt class="literal"><span class="pre">vbfunctions.IsMissing</span></tt> function to provide initialization of missing arguments within the body of the subroutine. This functionality is transparent under normal conditions, but if the subroutine manually assigns a value to the missing parameter prior to the IsMissing call then the behaviour may not match that of VB, since the <tt class="literal"><span class="pre">vbfunctions.IsMissing</span></tt> function has no way to detect that the parameter was not supplied.</p>
<p>VB:</p>
<pre class="literal-block">
Dim moduleGlobal1, moduleGlobal2

Sub MySub(X, Optional Y, Optional Z=20)
    Dim subLocal
    If IsMissing(Y) Then Y = 12
    subLocal = X + Y + Z + moduleGlobal
    moduleGlobal2 = moduleGlobal2 + 1
End Sub

MySub 1, 2
MySub 1, Z:=10
</pre>
</div>
<div class="section" id="argument-passing">
<h2><a name="argument-passing">Argument Passing</a></h2>
<p>VB has two argument passing schemes,</p>
<ol class="arabic simple">
<li><tt class="literal"><span class="pre">ByRef</span></tt> (Default) - arguments are passed by reference. Changes to the value inside the
subroutine are reflected in the corresponding parameter in the calling scope.</li>
<li><tt class="literal"><span class="pre">ByVal</span></tt> - arguments are passed by value. Changes to the value inside the subroutine do
not affect the parameter in the calling scope.</li>
</ol>
<p>Although Python's argument passing semantics are often refered to as pass-by-reference, the actual behaviour does not always match VB's <tt class="literal"><span class="pre">ByRef</span></tt> because of immutable object types and name re-binding. Although there are technical solutions for these issues, the current version of vb2Py does not make any attempt to match behaviours.</p>
<p><strong>This means that the following code, although converted, does not behave the same in the Python version</strong></p>
<p>VB:</p>
<pre class="literal-block">
Sub DoIt(x, ByVal y)
    x = x + 1
    y = y + 1
End Sub

x = 0
y = 0
DoIt x, y
' x is now 1, y is still 0
</pre>
</div>
</div>
<div class="section" id="list-of-options">
<h1><a name="list-of-options">List of Options</a></h1>
<p>There are no options specific to the <tt class="literal"><span class="pre">Sub</span></tt> statement.</p>
</div>
</div>
</body>
</html>
